Crate imxrt_iomuxc

source ·
Expand description

imxrt-iomuxc is a library for configuring i.MX RT processor pads. Using its API, you can

  • configure a pad for a peripheral, and specify its electrical properties.
  • manage pad objects as ownable resources.
  • statically constrain pads to work with peripherals.

As an end user, you’re expected to use imxrt-iomuxc through a hardware abstraction layer (HAL) or board support package (BSP). Specifically, you should have access to pad structs and objects, and you should be able to configure pads with the configure APIs.

As a library developer who writes HALs or hardware drivers, you may use the imxrt-iomuxc pin traits in your APIs to statically ensure pad-peripheral compatibility. See the design guidance for examples on how to achieve this.

§Definitions

A ‘pad’ is the physical input / output on an i.MX RT processor. Pads may be configured for various functions. A pad may act as a UART pin, an I2C pin, or other types of pins. A ‘pin’ is a pad that’s configured for a functional purpose. The traits let us say which pad can be used for which peripheral pin.

§Features

Processor pads, and their pin implementations, are enabled with optional feature flags. For example, the imxrt1060 feature flag exposes an imxrt1060 module that defines all i.MX RT 1060 processor pads. Users and integrators are responsible for making sure an enabled feature makes sense for their system.

§Design Guidance

For recommendations on how you can use these traits, see the module-level documentation. The rest of this section describes general guidance for designing APIs with these traits.

§Matching pads and peripherals

The pin traits allow you to restrict the pads and peripherals that comprise a peripheral. This lets you catch invalid peripheral configurations at compile time.

In the example below, we implement a hypothetical lpuart_new function, which is responsible for preparing a LPUART peripheral. To properly configure the peripheral, we need the two pads that represent a peripheral’s TX and RX pins. The implementation will use the imxrt_iomuxc::lpuart::prepare() function to prepare the pins.

Note the trait bounds on lpuart_new. The usage requires that

  • the user provides one TX and one RX pin
  • the modules for each pin match
use imxrt_iomuxc as iomuxc;
use iomuxc::lpuart::{Pin, Tx, Rx};

/// Creates a UART peripheral from the TX and RX pads
fn lpuart_new<T, R, const N: u8>(mut tx: T, mut rx: R) -> Lpuart<N>
where
    T: Pin<Direction = Tx, Module = iomuxc::consts::Const<N>>,
    R: Pin<Direction = Rx, Module = <T as Pin>::Module>,
{
    iomuxc::lpuart::prepare(&mut tx);
    iomuxc::lpuart::prepare(&mut rx);
    // Prepare the rest of the peripheral, and return it...
}

// GPIO_AD_B0_13 and GPIO_AD_B0_12 are a suitable pair of UART pins
lpuart_new(gpio_ad_b0_12, gpio_ad_b0_13);

Specifically, the trait bounds guard against non-UART pins:

ⓘ
// Neither pad is a valid UART pin
lpuart_new(gpio_ad_b0_10, gpio_ad_b0_11);

It also guards against mismatched UART pins:

ⓘ
// GPIO_AD_B1_02 is a UART2 TX pin, but GPIO_AD_B0_13 is a UART1 RX pin
lpuart_new(gpio_ad_b1_02, gpio_ad_b0_13);

§Type-Erased Pads

At the expense of requiring unsafe, users may favor type-erased pads over strongly-typed pads. When creating APIs that consume strongly-typed pads, or pads that conform to peripheral pin interfaces, consider supporting an unsafe API to create the peripheral without requiring the strongly-typed pads. The API will expect that the user is responsible for manually configuring the type-erased pad.

use imxrt_iomuxc::{self as iomuxc, ErasedPad, lpuart::{Pin, Tx, Rx}};

impl<const N: u8> Lpuart<N> {
    pub fn new<T, R>(mut tx: T, mut rx: R, /* ... */) -> Self
    where
        T: Pin<Direction = Tx, Module = iomuxc::consts::Const<N>>,
        R: Pin<Direction = Rx, Module = <T as Pin>::Module>,
    {
        imxrt_iomuxc::lpuart::prepare(&mut tx);
        imxrt_iomuxc::lpuart::prepare(&mut rx);
        // ...
    }

    pub fn with_erased_pads(tx: ErasedPad, rx: ErasedPad, /* ... */) -> Self {
        // ...
    }
}

// Preferred: create a LPUART peripheral with strongly-typed pads...
let gpio_ad_b0_13 = unsafe { GPIO_AD_B0_13::new() };
let gpio_ad_b0_12 = unsafe { GPIO_AD_B0_12::new() };
let uart1 = Lpuart::<1>::new(gpio_ad_b0_12, gpio_ad_b0_13);

// Optional: create a LPUART peripheral from type-erased pads...
let gpio_ad_b0_13 = unsafe { GPIO_AD_B0_13::new() };
let gpio_ad_b0_12 = unsafe { GPIO_AD_B0_12::new() };

let mut rx_pad = gpio_ad_b0_13.erase();
let mut tx_pad = gpio_ad_b0_12.erase();

// User is responsible for configuring the pad,
// since we can't call `prepare()` on the pad...
unsafe {
    // Daisy registers and values aren't attached
    // to erased pads, so we have to reference this
    // manually.
    <GPIO_AD_B0_13 as imxrt_iomuxc::lpuart::Pin>::DAISY.map(|daisy| daisy.write());
    <GPIO_AD_B0_12 as imxrt_iomuxc::lpuart::Pin>::DAISY.map(|daisy| daisy.write());
}
imxrt_iomuxc::alternate(&mut tx_pad, 2);
imxrt_iomuxc::alternate(&mut rx_pad, 2);
imxrt_iomuxc::clear_sion(&mut tx_pad);
imxrt_iomuxc::clear_sion(&mut rx_pad);
// Pads are configured for LPUART settings
let uart1 = Lpuart::<1>::with_erased_pads(tx_pad, rx_pad);

Modules§

  • adc
    ADC pad configuration
  • ccm
    CCM pad configuration.
  • consts
    Type-level constants and traits.
  • flexcan
    FlexCAN pad configurations
  • flexio
    FlexIO pad configurations
  • flexpwm
    PWM pad configuration
  • gpio
    GPIO pad configuration
  • imxrt1010imxrt1010
    Pads for the i.MX RT 1010 processor family
  • imxrt1020imxrt1020
    Pads for the i.MX RT 1020 processor family
  • imxrt1060imxrt1060
    Pads for the i.MX RT 1060 processor family
  • imxrt1170imxrt1170
    Pads for the i.MX RT 1170 processor family.
  • lpi2c
    I2C pad configuration
  • lpspi
    SPI pad configurations
  • lpuart
    UART pad configuration
  • prelude
    Re-export of top-level components, without the chip-specific modules.
  • sai
    SAI / I2S pad configurations
  • usdhc
    USDHC pad configuration

Structs§

  • Config
    A configuration capable of compile-time, const configuration:
  • Daisy
    A daisy selection
  • ErasedPad
    A pad that has its type erased
  • Pad
    An i.MXT RT pad
  • WrongPadError
    An error that indicates the conversion from an ErasedPad to a strongly-typed pad failed.

Enums§

  • DriveStrength
    Drive strength
  • Hysteresis
    The hysteresis (HYS) bit controls whether a pin acts as a Schmitt trigger, which is a comparator remembering its last input state (hysteresis).
  • OpenDrain
    Open Drain Enable Field
  • PullKeepDeprecated
    Enable or disable the pull / keeper functionality
  • PullKeepSelectDeprecated
    Control signal to enable internal pull-up/down resistors or pad keeper functionality.
  • PullKeeper
    The pull up, pull down, or keeper configuration.
  • PullUpDownDeprecated
    Controls signals to select pull-up or pull-down internal resistance strength.
  • SlewRate
    Slew Rate
  • Speed
    Sets electrical characteristics of a pin in a given frequency range

Traits§

  • Iomuxc
    An IOMUXC-capable pad which can support I/O multiplexing

Functions§

  • alternate
    Set an alternate value for the pad
  • clear_sion
    Clear the SION bit in a pad’s MUX register
  • configure
    Applies the configuration config for the supplied pad
  • set_sion
    Set the SION bit in a pad’s MUX register